-
Couldn't load subscription status.
- Fork 13.9k
rustdoc: add support for macro_rules macros of multiple kinds #148005
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: master
Are you sure you want to change the base?
rustdoc: add support for macro_rules macros of multiple kinds #148005
Conversation
This adds support for advanced RFC 3697 and 3698 macros, that look
like this:
```
/// Doc Comment.
macro_rules! NAME {
attr(key = $value:literal) ($attached:item) => { ... };
derive() ($attached:item) => { ... };
($bang:tt) => { ... };
}
```
And can be used like this:
```
/*attr*/ #[NAME]
/*derive*/ #[derive(NAME)]
/*bang*/ NAME!{}
```
The basic problem is that there are three different ways to use
this macro, and, historically, these three ways were implemented
by fully-separated proc macro items with separate doc comments.
We want these new declarative macros to work the same way,
so they appear in the same section of the module table of contents
and can be filtered for in the search engine.
This commit makes the feature work by generating separate pages
for each macro kind. These separate pages appear in separate
sections of the module table of contents, produce separate
search results, and have duplicate copies of the doc comment.
The following features would also be helpful, but are left
for future commits to implement:
- To improve the produced documentation, we should probably add
support for adding `///` attributes to macro rules arms, so that
the different syntaxes can actually be documented separately.
- This commit doesn't test intra-doc links.
Parts of rust-lang#145458 are directly
used in this code.
Co-Authored-By: Guillaume Gomez <guillaume1.gomez@gmail.com>
|
Although I find the result of this approach less good (ie, duplicated files generated for the same macro), considering how much easier the implementation is, I'd prefer for this one to be merged. I'll close #145458. |
|
Btw, the PR looks ready to me so feel free to r=me unless you want to make more changes. |
|
rustdoc-json-types is a public (although nightly-only) API. If possible, consider changing cc @CraftSpider, @aDotInTheVoid, @Enselic, @obi1kenobi Some changes occurred in GUI tests. Some changes occurred in HTML/CSS/JS. |
|
rustbot has assigned @GuillaumeGomez. Use |
|
I know you have already looked at the code a little bit. Can you check it and make sure I'm using the bitflags correctly? |
This adds support for advanced RFC 3697 and 3698 macros, that look like this:
And can be used like this:
The basic problem is that there are three different ways to use this macro, and, historically, these three ways were implemented by fully-separated proc macro items with separate doc comments. We want these new declarative macros to work the same way, so they appear in the same section of the module table of contents and can be filtered for in the search engine.
This commit makes the feature work by generating separate pages for each macro kind. These separate pages appear in separate sections of the module table of contents, produce separate search results, and have duplicate copies of the doc comment.
The following features would also be helpful, but are left for future commits to implement:
To improve the produced documentation, we should probably add support for adding
///attributes to macro rules arms, so that the different syntaxes can actually be documented separately.This commit doesn't test intra-doc links.
Parts of #145458 are directly used in this code.
cc @joshtriplett @GuillaumeGomez @lolbinarycat